API Design Pattern of the Week 15: Rate Limit
A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”
The first 14 patterns in the “API Design Pattern of the Week” series came as LinkedIn articles. All patterns in the series are listed in this overview story.
Note: This online excerpt of the pattern predates the final version in the book.
Context
An API endpoint and the API contract defining operations, messages, and data representations have been established. An API Description has been defined that specifies messages exchange patterns and protocol. Clients of the API might have signed up with the provider and have agreed to the terms and conditions that govern the usage of the endpoint.
Problem
How can the API provider prevent API clients from excessive API usage?
What exactly is deemed excessive needs to be defined by the API provider. A flat rate subscription typically imposes different limitations than a free billing plan. See the Pricing Plan pattern for a detailed discussion of the trade-offs of different subscription models.
Forces
When preventing excessive API usage that may harm provider operations or other clients, solutions to the following design issues have to be found:
- Economic aspects
- Performance
- Reliability
- Impact and severity of risks of API abuse
- Client awareness
These pattern forces are explained in depth in the book.
Solution Sketch
Introduce and enforce a Rate Limit to safeguard against API clients that overuse the API.
Example
GitHub uses this pattern to control access to its RESTful HTTP API: Once a Rate Limit is exceeded, subsequent requests are answered with HTTP status code 429 Too Many Requests. To inform clients about the current state of each Rate Limits and to help clients manage their allowance of tokens, custom HTTP headers are sent with each rate-limited response.
The following code listing shows an excerpt of such a rate-limited response from the GitHub API. The API has a limit of 60 requests per hour, of which 59 remain:
GET https://api.github.com/users/misto
HTTP/1.1 200 OK ...
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1498811560The X-RateLimit-Reset indicates the time when the limit will be reset with a Unix timestamp (Unix timestamps count the number of seconds since January 1st, 1970).
Consequences
Forces resolution and other consequences are discussed in our book.
Known Uses
See pattern coverage on our website api-patterns.org.
Related Patterns
The details of a Rate Limit can be part of a Service Level Agreement. A Rate Limit can be dependent on the client’s subscription level, which is further described in the Pricing Plan pattern. In such cases the Rate Limit is used to enforce different billing levels of the Pricing Plan.
To observe individual clients and manage their allowances, the service provider needs to identify the client making a request. Therefore, clients need to present some form of identification (e.g. an API Key, an IP address or another authentication practice) so that the API provider can do the bookkeeping.
A Wish List and a Wish Template can help to ensure that data-bound Rate Limits are not violated. The current state of the Rate Limit, e.g., how many requests remain in the current billing period, can be communicated via a Context Representation.
The systems management patterns (Hohpe and Woolf 2003) can help to implement metering and can thus also be used as enforcement points. For example, a Control Bus can be used to increase or decrease certain limits dynamically at runtime. Leaky Bucket Counter (Hanmer 2007) offers a possible implementation variant for Rate Limit.
References
Hanmer, Robert. 2007. Patterns for Fault Tolerant Software. Wiley.
Hohpe, Gregor, and Bobby Woolf. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.
Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.
This pattern originally appeared on the https://api-patterns.org website.
The pattern presentation follows the standard format for patterns, from context to forces, problem, solution, consequences and known uses. Find out why.
Copyright © 2019–2023 by the authors.
All rights reserved.
See terms and conditions of use.
